home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48hor1 / db48.doc < prev    next >
Text File  |  1995-03-31  |  16KB  |  352 lines
  1.  
  2. 6/11/91                            DB48.DOC 
  3.                           Copyright 1990 Ross Barnes 
  4.  
  5. This document is for: 
  6.  
  7. DB48 Version 2.11 
  8. Program size: 8277 bytes 
  9. Checksum: #16370d 
  10. Romid: 769 
  11.  
  12. OVERVIEW 
  13. -------- 
  14.  
  15. DB48 is a library containing a database system for the HP48SX.  You can create 
  16. any number of databases with one to ? fields in each database.  Once a database 
  17. is created you can add, view, modify, or delete records.  The first record in  
  18. a database CAN be edited but CANNOT be deleted.  This record is used for the 
  19. field names in the database.  All records are alphabetized  by the first field.   
  20. You can find a record using the keyed first field or find a string anywhere  
  21. in the database.  You can scroll through the records or jump to the end or  
  22. back to the beginning.  Records can be copied to and from the stack.   
  23.  
  24. ** Databases must be in user memory. ** 
  25.  
  26. USAGE POLICY 
  27. ------------ 
  28. The DB48 library and its documentation are Copyright 1990 Ross Barnes, 
  29. all rights reserved. 
  30.  
  31. DB48 is "shareware". 
  32.  
  33. The DB48 library and documentation may be distributed freely by individuals  
  34. and BBS operators as long as the library and documentation (both unmodified) 
  35. are provided TOGETHER. 
  36.  
  37. Individuals may use DB48 for two weeks.  If DB48 is something you will continue  
  38. to use then register it.  The cost is $10 (cash or money order, no checks).   
  39. See SUPPORT for registration benefits.   
  40.  
  41. Corporate or institutional use is prohibited. 
  42.  
  43. The sale of DB48 for profit, either alone or together with other software  
  44. or hardware is prohibited.  
  45.  
  46. SUPPORT 
  47. ------- 
  48.  
  49. General Support - All letters to the author will be answered.  If you have a  
  50.                   problem using the library send me a letter.  If you decide  
  51.                   not to register let me know why.  A newer version of DB48  
  52.                   may be available to answer your complaints.   
  53.  
  54. Registered Support - In addition to the support above the registered users  
  55.                      will be notified of bugs and bug fixes, as  
  56.                      well as limited telephone support (my home number -  
  57.                      available evenings and weekends).  They will also 
  58.                      be notified of the availability of new versions  
  59.                      of DB48.  Registered users can have the library id of DB48 
  60.                      changed if there is a conflict with another rom card or 
  61.                      library.  Registered users will receive priority for 
  62.                      correspondence. 
  63.  
  64. Address all correspondence to the author: 
  65.  
  66. Ross Barnes 
  67. 8412 N. Boone #104 
  68. Kansas City, MO 64155 
  69.  
  70. DISCLAIMER 
  71. ---------- 
  72. The author shall not be liable for any damages, incidental or consequential, 
  73. resulting from the use of DB48. 
  74.  
  75. PROCEDURE  
  76. --------- 
  77.  
  78. 1.  Transfer the library to your HP 48.   
  79.  
  80. 2.  Recall the library object and store it to a RAM port (:p:x STO, where 
  81.     p is the port number (0, 1, or 2) and x is any number.  You can now  
  82.     purge the original variable. 
  83.  
  84. 3.  Turn the HP48 off, then on.  This adds the library to the system table. 
  85.     Making sure you are in the root directory execute 769 ATTACH. 
  86.  
  87. 4.  To start the program type DODB [ENTER]. 
  88.  
  89. 5.  The program prompts you for a database name: 
  90.     New database name? 
  91.     .DB 
  92.  
  93. 6.  Enter a name, e.g. TELE.DB [ENTER].  Do not use quotes around name.  Using 
  94.     .DB as the extension will allow the program to detect databases in the  
  95.     current directory. 
  96.  
  97. 7.  It prompts you for the number of fields: 
  98.     Number of fields? 
  99.  
  100. 8.  Enter a number from 1 to ?.  The first 5 fields can always be seen.  Use 
  101.     [ENTER] or [left-shift][ENTER] to view any field.  If 3 was entered the  
  102.     display will now have: 
  103.  
  104.     FLD1 
  105.     FLD2 
  106.     FLD3 
  107.  
  108.     in the display.  This is the first record in the database.  This record 
  109.     contains the field names.  It can be edited but not deleted.  When the 
  110.     database is sorted this record will remain at the top. 
  111.  
  112. 9.  At this time the database has been created.  It contains one record. 
  113.     All database functions are active.  To add new records press {ADD}. 
  114.     The functions of the database and the keys necessary to access them 
  115.     are described below.    
  116.  
  117. MENU KEYS 
  118. --------- 
  119.  
  120. {USE}    --Finds all the variables with .DB in the name, prompts for a  
  121.            database to use.  Select a database and [ENTER]. 
  122.  
  123. {FIND}   --Prompts for a fast find string and uses a binary search 
  124.            of the first field to find the record with a first field equal 
  125.            to or greater than the fast find string.  The last fast find string  
  126.            is remembered for the current database.  The first record in the 
  127.            database is not included in binary searches.   
  128.  
  129. [left-shift] 
  130. { FIND } --Prompts for a slow find string and sequentially  
  131.            searches for the string throughout every field in every record 
  132.            starting at the current record plus one to the end of database. 
  133.            To search the entire database [right-shift][up-arrow] first to  
  134.            go to the top then [left-shift]{ FIND }.  The search IS CASE  
  135.            SENSITIVE.  Using only uppercase letters in the database is  
  136.            probably a good idea.  If the string is found the record containing 
  137.            the string is displayed.  If the string is not found the current 
  138.            record will be redisplayed. 
  139.  
  140. {EDIT}   --Prompts for a field to edit while displaying all the fields as 
  141.            menu keys.  Select a field and [ENTER].  You are prompted with  
  142.            the field name and a ?.  The default input is the current field's  
  143.            value.  Be sure to turn off alpha when using the edit menu or 
  144.            for the following menu.  {right-shift}{ MENU } (last menu) will  
  145.            bring up a menu of common punctuation: 
  146.                        [ ? ][ ! ][ @ ][ & ][ $ ][cents]. 
  147.            Once you are through editing the field, press [ENTER] and the 
  148.            program will prompt you to save changes.  Enter Y or N and 
  149.            [ENTER]. 
  150.             
  151. [left-shift] 
  152. {EDIT}   --Brings up the first field name prompt followed by a ?. 
  153.            The default input is the current field's value.  All fields are 
  154.            prompted for in consecutive order.  The other menus mentioned in 
  155.            {EDIT} are also available. 
  156.  
  157. {ADD}    --Adds a record to the current database and then edits the record. 
  158.  
  159. [left-shift] 
  160. {ADD}    --A new list of menu keys are displayed. 
  161.  
  162.   {+DB}  --Creates a new database, prompting for the name and the 
  163.            number of fields in the new database.  This database 
  164.            is now the current database. 
  165.  
  166.   {+REC} --Adds a record to the current database and then edits the record. 
  167.  
  168.   {+FLD} --Adds a new field to every record in the database.  This field 
  169.            is appended to the end of the record and is empty except for 
  170.            record one which has "NEW FLD" as its value. 
  171.  
  172.   {UP}   --Returns to menu containing {ADD}. 
  173.  
  174. {DEL}    --Prompts to delete current record.  Select "Y" or "N" and [ENTER]. 
  175.            If "Y" is selected the current record will be deleted. 
  176.  
  177. [left-shift] 
  178. {DEL}    --A new list of menu keys are displayed. 
  179.  
  180.   {-DB}  --Prompts for a database to delete while displaying all databases 
  181.            in current directory as menu keys.  Select a database and [ENTER]. 
  182.            Once a database is selected it is PURGED immediately.  You cannot  
  183.            delete the current database. 
  184.  
  185.   {-REC} --Prompts to delete current record.  Select "Y" or "N" and [ENTER]. 
  186.            If "Y" is selected the current record will be deleted. 
  187.  
  188.   {-FLD} --Prompts for a field to delete in current database while displaying 
  189.            all fields in current database as menu keys.  Select a field and 
  190.            [ENTER].  The selected field will be deleted from all records. 
  191.  
  192.   {UP}   --Returns to menu containing {DEL}. 
  193.  
  194. {EXIT}   --This exits the program. 
  195.  
  196. {ABOUT}  --Version, author and copyright notice. 
  197.  
  198. [left-shift] 
  199. {ABOUT}  --Displays number of records in database, amount of  
  200.                        RAM occupied by database and free RAM. 
  201.  
  202. {->STK}  --Copies current record to top of stack.  This can be used with  
  203.            {->DB} to copy a record from one database to another. 
  204.  
  205. [left-shift] 
  206. {->STK}  --Copies each field of current record to stack tagging them 
  207.            with field names.  
  208.  
  209. {->DB}   --Add new record to database by copying record from top of stack. 
  210.            If record on stack contains more fields than current database  
  211.            the excess fields are deleted.  If record on stack contains 
  212.            fewer fields than current database the extra fields are initialized 
  213.            to empty. 
  214.  
  215. [left-shift] 
  216. {->DB}   --Replaces current record with record on top of stack. 
  217.  
  218. {CIPHER} --Encodes/decodes a field in the current record.  You are 
  219.            prompted for a field and a key.  The field is then encoded/decoded. 
  220.            You cannot encode/decode the first field (sort field). 
  221.            Once you have ciphered the field, the program will 
  222.            prompt you to save changes.  Enter Y or N and [ENTER]. 
  223.                          
  224. {SORT}   --Sorts current database using first field as key.  This should 
  225.            not be necessary in normal circumstances.  The program keeps 
  226.            the database sorted for you in most cases.  If you have an 
  227.            unsorted database (you created on your own) this command will sort 
  228.            it for you.  The sort is slow.  Thirty seconds for thirty records. 
  229.            Use a PC to sort large databases (>50 records) unless you have  
  230.            lots of memory and time.  Record one is never included in the  
  231.            sort since it contains the field names. 
  232.  
  233. OTHER KEYS 
  234. ---------- 
  235.  
  236. [alpha]  --Pressing the alpha key followed by a letter key will find a record 
  237.            in which the first field starts with the letter pressed.  For 
  238.            example, [alpha][F] will find a record whose first field 
  239.            starts with "F" or letter after "F". 
  240.  
  241. [NXT]    --Moves to next menu on current level. 
  242.  
  243. [ENTER]  --Prompts for field to display of current record.  Select a field 
  244.            [ENTER]. 
  245.  
  246. [left-shift] 
  247. [ENTER]  --Displays each field of current record.  Press any key to display 
  248.            field. 
  249.  
  250. [up arrow] --Move up one record in current database. 
  251.  
  252. [left-shift] 
  253. [up arrow] --Moves to the top of the database briefly displaying  
  254.              each record.  Press any key (except ON) to stop. 
  255.  
  256. [right-shift] 
  257. [up arrow] --Moves to top of current database. 
  258.  
  259. [down arrow] --Move down one record in current database. 
  260.  
  261. [left-shift] 
  262. [down arrow] --Moves to the bottom of the database briefly displaying  
  263.                each record.  Press any key (except ON) to stop. 
  264.  
  265. [right-shift] 
  266. [down arrow] --Moves to bottom of current database. 
  267.  
  268. HELPFUL HINTS AND WARNINGS 
  269. -------------------------- 
  270.  
  271. If you are "low" on free memory (1.25 times the size of the current database)  
  272. certain operations ADD, DEL, EDIT, SORT, and ->DB will not be allowed because 
  273. they would fail.  This is to help prevent corruption of a database.  Nothing 
  274. can be tested for every circumstance so REMEMBER TO BACK UP YOUR DATABASES! 
  275.  
  276. Once you have created a database {EDIT} the first record 
  277. and change the field names to something more meaningful.   
  278.  
  279. If you are asked for input [ENTER]ing an empty string will, in most cases, 
  280. abort the action.  An exception to this is a field EDIT or record ADD. 
  281.  
  282. If you are editing a field but change your mind then just press [ENTER] 
  283. and when it asks you to save changes enter N. 
  284.  
  285. If you are asked for input and there is a default value you can hit the [ON] 
  286. key to clear the default input.  Be careful not to press the [ON] key more 
  287. than once or the program will be terminated. 
  288.  
  289. Always use a .DB for the database names so they will show up in the {USE} 
  290. menu keys...unless you are trying to hide it. 
  291.  
  292. To copy a record from one database to another {->STK} to copy record from 
  293. database to stack, {USE} the new database and {->DB} to copy the record from  
  294. stack to database.   
  295.  
  296. ------------------------------------------------------------------------------- 
  297. NOTE: The variable DBINFO is created if it does not already exist 
  298. in the current directory.  This variable contains a list consisting of the 
  299. current active database in the current directory, the current record number 
  300. and the last find string.  If an error occurs when you try to run the  
  301. program check the DBINFO variable and if invalid purge it and rerun  
  302. the program.  
  303. ------------------------------------------------------------------------------- 
  304.  
  305. RECOVERY HELP!!! 
  306. ---------------- 
  307. If the program crashes or you accidentally pressed the [ON] key and halted the  
  308. program you may have corrupted the current database.  RCL your database  
  309. variable to the stack.  If it only contains the first record (field names) then  
  310. you will have to try to recover the records off the stack.  Use [up arrow] key  
  311. to examine the stack.  Remove all non-record entries from the stack.  Determine  
  312. the number of records on the stack using DEPTH.  Recreate the old database with 
  313. ->LIST.  Save it to the database variable.  You should then execute [SORT] 
  314. from inside DB48 to make certain the database is properly ordered.   
  315.  
  316. ** REMEMBER TO BACKUP YOUR DATABASES!! ** 
  317.  
  318. Version Info 
  319. ------------ 
  320. Version 2.11 - Fixes problem that occurs when {ADD}ing a record or using 
  321.                [left-shift]{EDIT} but answering N to save changes? 
  322.  
  323. Version 2.10 - Modified EDIT to not keep entire DB on stack - slower but safer. 
  324.                Added CIPHER menu option to encode a field. 
  325.                Added save changes prompt when editing a field or ciphering 
  326.                a field. 
  327.                Added alpha+"letter" to jump to record whose first field starts 
  328.                with "letter". 
  329.  
  330. Version 2.01 - Fixes a problem with garbage left on stack after entering "" for 
  331.                a [left-shift] {FIND} (slow find). 
  332.  
  333. Version 2.0  - Major improvements over 1.0. Implemented sorted databases with 
  334.                binary search.  The program was made into a library rather than  
  335.                run from a directory.  Available memory is constantly monitored 
  336.                to prevent database operations from failing.  Many other  
  337.                features were added or improved. 
  338.  
  339.                Converting 1.0 databases to 2.0 is straightforward.  The 2.0 
  340.                databases are sorted, 1.0 databases are not.  Use the following 
  341.                procedure to sort the 1.0 databases: 
  342.  
  343.                Start DB48 Version 2.0.  {USE} the version 1.0 database.   
  344.                Once the 1.0 database is the current database, press 
  345.                [NXT] and {SORT}.  This will sort the old database on the  
  346.                first field.  This sort is slow.  Once the sort is completed  
  347.                you can use all the features of 2.0. 
  348.  
  349. Version 1.0  - The original program for the HP48.  Searches were sequential. 
  350.                The program was in a directory in :0, :1, or :2.  Few features. 
  351.                 
  352.